package org.javanum.number;

/**
 * <p>Defines an abstract Field</p>
 * 
 * <p>A <i>Field</i> is defined as a <i>commutative Division Ring with unit</i>.
 *  In other words, a Field is a set {@code S} together with two operations 
 *  {@code +} and {@code *} which satisfies the following rules:</p>
 *  
 *  <p>1. <i>Abelian Group under +:</i> {@code S}, together with the operation 
 *  {@code +}, forms an Abelian Group. Thus, it is a {@link Group} which also
 *  satisfies the rule that, for any elements {@code a} and {@code b} in 
 *  {@code S}, then {@code a+b=b+a}. For more information, see {@link Group}</p>
 *  
 *  <p>2. <i>Ring under * and +:</i> {@code S}, together with {@code +} and
 *  {@code *}, form a {@link Ring}</p>
 *  
 *  <p>3. <i>Multiplicative Identity:</i> There is an element {@code e} in
 *  {@code S} such that, for any "non-zero element" {@code a} in {@code S}, 
 *  then {@code a*e=e*a=a}</p>
 *  
 *  <p>4. <i>Multiplicative inverse:</i> for every "non-zero element" {@code a}
 *  in {@code S}, there is another element {@code b} such that {@code a*b=b*a=e}
 *  , where {@code e} is the multiplicative identity.</p>
 *  
 *  
 *  <p>an element is called "zero" if it is the additive identity in {@code S}.
 *  Thus it is important to notice that the multiplication rules governing 
 *  inversion(and therefore division) do not apply to the additive identity.</p>
 *  
 *  
 * @author Scott Fines
 * Date: Oct 23, 2009
 *
 * @param <T> The Field element type which can be processed. Since the 
 * Field operations need only apply to elements within the Field itself, this
 * parameter specifies which field the element belongs to in a type-safe manner.
 */
public interface Field<T extends Field<T>>extends Ring<T>{
	
	/**
	 * {@inheritDoc Ring.multiply}.
	 * <p>Since fields are commutative under multiplication, the ordering of this
	 * method is irrelevant. That is, {@code this*value = value*this}.</p>
	 */
	public T multiply(T value);
	/**
	 * <p>Divides {@code this} by the element {@code divisor}.</p>
	 * 
	 * <p>The division operation is defined as multiplication of {@code this}
	 * by the multiplicative inverse of {@code divisor}.</p>
	 * 
	 * <p>Order here is relevant, even though multiplication is commutative in 
	 * fields, since {@code this/divisor !=divisor/this} in general.</p>
	 * 
	 * @param divisor the element to divide by
	 * @return the result of the computation 
	 * 			{@code this/divisor = this*Math.pow(divisor,-1)}
	 * @throws ArithmeticException if {@code divisor} is the additive identity in the
	 * field.
	 */
	public T divide(T divisor);
	
	/**
	 * <p>Returns the multiplicative identity for this field. </p>
	 * 
	 * <p>The multiplicative identity is defined as the element {@code e} such
	 * that {@code a*e=e*a=a} for any non-zero field element {@code a}</p>
	 * 
	 * @return the multiplicative identity element for this field.
	 */
	public  T multiplicativeIdentity();
	
	/**
	 * <p>Returns the multiplicative inverse of {@code this}.</p>
	 * 
	 * <p>If the object returned by this method is {@code b}, then 
	 * 	{@code this*b=b*this=}{@link #multiplicativeIdentity()}</p>
	 * 
	 * @return the multiplicative inverse of {@code this}.
	 */
	public T multiplicativeInverse();

}
